ModelicaReference.Classes

In this package specialized kinds of classes (earlier known as restricted classes) are described. They have the properties of a general class, apart from restrictions. Moreover, they have additional properties called enhancements.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

Package Content

Name	Description
'block'	block
'class'	class
'connector'	connector
ExternalObject	ExternalObject
'function'	function
'model'	model
'package'	package
'record'	record
'type'	type

ModelicaReference.Classes.'block'

Define specialized class block

Examples

block Integrator
  input Real u;
  output Real y;
protected
  Real x;
equation
  der(x) = u;
  y = x;
end Integrator;

Syntax

   [ encapsulated ][ partial ] block
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

A block class is the same as a model class with the restriction that each connector component of a block must have prefixes input and/or output for all connector variables. The purpose is to model input/output blocks of block diagrams. Due to the restrictions on input and output prefixes, connections between blocks are only possible according to block diagram semantic.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.'class'

Define class

Examples

class MyTable
  extends ExternalObject;
  function constructor
     ...
  end constructor;

  function destructor
     ...
  end destructor;
end MyTable;

Syntax

   [ encapsulated ][ partial ] class
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

The keyword class is used to define general classes (without any restrictions). It is identical to the keyword model. In most cases, it is recommended to use specialized classes as connector, model, block, package, record, function, type. "class" should be used to define ExternalObjects, and can be used for classes merely containing documentation and/or graphics.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.'connector'

Define specialized class connector

Examples

connector flange
  Modelica.SIunits.Angle phi;
  flow Modelica.SIunits.Torque tau;
end flange;

Syntax

   [ encapsulated ][ partial ] connector
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

The keyword connector is used to define connectors, which are used in connect() statements. In connectors, no equations are allowed in the definition or in any of its components. With respect to "class", it is enhanced to allow connect(..) to components of connector classes.

Variable declarations in a connector can have the additional prefixes flow or stream, besides the prefixes input and output, that are also allowed outside of a connector. Based on the prefix, a connect() statement leads to specific connection equations, that describe the balance equations in the infinitesimal connection points.

Example

If three connectors c1, c2, c3 with the definition

connector Demo
  Real        p;  // potential variable
  flow   Real f;  // flow variable
  stream Real s;  // stream variable
end Demo;

are connected together with

   connect(c1,c2);
   connect(c1,c3);

then this leads to the following equations:

  // Potential variables are identical
  c1.p = c2.p;
  c1.p = c3.p;

  // The sum of the flow variables is zero
  0 = c1.f + c2.f + c3.f;

  /* The sum of the product of flow variables and upstream stream variables is zero
     (this implicit set of equations is explicitly solved when generating code;
     the "<undefined>" parts are defined in such a way that
     inStream(..) is continuous).
  */
  0 = c1.f*(if c1.f > 0 then s_mix else c1.s) +
      c2.f*(if c2.f > 0 then s_mix else c2.s) +
      c3.f*(if c3.f > 0 then s_mix else c3.s);

  inStream(c1.s) = if c1.f > 0 then s_mix else <undefined>;
  inStream(c2.s) = if c2.f > 0 then s_mix else <undefined>;
  inStream(c3.s) = if c3.f > 0 then s_mix else <undefined>;

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.ExternalObject

Define external functions with internal memory.

Description

External functions may have internal memory reported between function calls. Within Modelica this memory is defined as instance of the predefined class ExternalObject according to the following rules:

• There is a predefined partial class ExternalObject [since the class is partial, it is not possible to define an instance of this class].
• An external object class shall be directly extended from ExternalObject, shall have exactly two function definitions, called "constructor" and "destructor", and shall not contain other elements.
• The constructor function is called exactly once before the first use of the object. For each completely constructed object, the destructor is called exactly once, after the last use of the object, even if an error occurs. The constructor shall have exactly one output argument in which the constructed ExternalObject is returned. The destructor shall have no output arguments and the only input argument of the destructor shall be the ExternalObject. It is not legal to call explicitly the constructor and destructor functions.
• Classes derived from ExternalObject can neither be used in an extends-clause nor in a short class definition.
• External functions may be defined which operate on the internal memory of an ExternalObject. An ExternalObject used as input argument or return value of an external C-function is mapped to the C-type "void*".

Examples

A user-defined table may be defined in the following way as an ExternalObject (the table is read in a user-defined format from file and has memory for the last used table interval):

class MyTable
  extends ExternalObject;
  function constructor
    input  String  fileName = "";
    input  String  tableName = "";
    output MyTable table;
    external "C" table = initMyTable(fileName, tableName);
  end constructor;

  function destructor "Release storage of table"
    input  MyTable table;
    external "C" closeMyTable(table);
  end destructor;
end MyTable;

and used in the following way:

model test "Define a new table and interpolate in it"
  MyTable table=MyTable(fileName ="testTables.txt",
                        tableName="table1");  // call initMyTable
  Real y;
equation
  y = interpolateMyTable(table, time);
end test;

This requires to provide the following Modelica function:

function interpolateMyTable "Interpolate in table"
  input  MyTable table;
  input  Real  u;
  output Real  y;
  external "C" y = interpolateMyTable(table, u);
end interpolateTable;

The external C-functions may be defined in the following way:

typedef struct {  /* User-defined data structure of the table */
  double* array;      /* nrow*ncolumn vector       */
  int     nrow;       /* number of rows            */
  int     ncol;       /* number of columns         */
  int     type;       /* interpolation type        */
  int     lastIndex;  /* last row index for search */
} MyTable;

void* initMyTable(const char* fileName, const char* tableName) {
  MyTable* table = malloc(sizeof(MyTable));
  if ( table == NULL ) ModelicaError("Not enough memory");
        // read table from file and store all data in *table
  return (void*) table;
}

void closeMyTable(void* object) { /* Release table storage */
  MyTable* table = (MyTable*) object;
  if ( object == NULL ) return;
  free(table->array);
  free(table);
}

double interpolateMyTable(void* object, double u) {
  MyTable* table = (MyTable*) object;
  double y;
  // Interpolate using "table" data (compute y)
  return y;
}

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.'function'

Define specialized class function

Examples

function si
  input Real x;
  output Real y;
algorithm
  y = if abs(x) < Modelica.Constants.eps then 1 else Modelica.Math.sin(x)/x;
end si;

Syntax

   [ encapsulated ][ partial ] function
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

The keyword function is used to define functions as known from programming languages. Each part of a function interface must either have causality equal to input or output. A function may not be used in connections. In functions, no equations or initial algorithm and at most one algorithm clause are allowed. Calling a function requires either an algorithm clause or an external function interface.

The syntax and semantics of a function have many similarities to those of the block specialized class. A function has many of the properties of a general class, e.g., being able to inherit other functions, or to redeclare or modify elements of a function declaration.

Modelica functions have the following restrictions compared to a general Modelica class:

• Each input formal parameter of the function must be prefixed by the keyword input, and each result formal parameter by the keyword output. All public variables are formal parameters.
• Input formal parameters are read-only after being bound to the actual arguments or default values, i.e., they may not be assigned values in the body of the function.
• A function may not be used in connections, may have no equations, may have no initial algorithm, and can have at most one algorithm section, which, if present, is the body of the function.
• A function may have zero or one external function interface, which, if present, is the external definition of the function.
• For a function to be called in a simulation model, it must have either an algorithm section or an external function interface as its body, and it may not be partial.
• A function cannot contain calls to the Modelica built-in operators der, initial, terminal, sample, pre, edge, change, reinit, delay, cardinality, to the operators of the built-in package Connections, and is not allowed to contain when-statements.
• The dimension sizes not declared with (:) of each array result or array local variable [i.e., a non-input components] of a function must be either given by the input formal parameters, or given by constant or parameter expressions, or by expressions containing combinations of those. If an output or a local array dimension is declared with (:), the size of the dimension can be changed in the function. A size change takes place by assigning a full array with the respective sizes to the dynamically sized array on the left hand side of an equal sign.
• The local variables of a function are not automatically initialized to the implicit default values of the data type [(e.g., 0.0 for Real) for performance reasons. It is the responsibility of the user to provide explicit defaults or to define the values of such variables before they are referenced.]
• Components of a function will inside the function behave as though they had discrete-time variability.

Modelica functions have the following enhancements compared to a general Modelica class:

• A function may be called using the conventional positional calling syntax for passing arguments.
• A function can be recursive.
• A formal parameter or local variable may be initialized through an assignment (:=) of a default value in its declaration. Initialization through an equation is not possible.
• A function is dynamically instantiated when it is called rather than being statically instantiated by an instance declaration, which is the case for other kinds of classes.
• A function may have an external function interface specifier as its body.
• A function may have a return statement in its algorithm section body.
• A function allows dimension sizes declared with (:) to be resized for non-input array variables (so the actual dimension need not to be known when the function is translated).

A function may have a function as an input argument. The declared type of such an input formal parameter in a function can be the class-name of a partial function that has no replaceable elements. It cannot be the class-name of a record [i.e., record constructor functions are not allowed in this context.] Such an input formal parameter of function type can also have an optional functional default value. Example:

function quadrature "Integrate function y=integrand(x) from x1 to x2"
  input  Real x1;
  input  Real x2;
  input  Integrand integrand;   // Integrand is a partial function, see below
  // With default: input Integrand integrand := Modelica.Math.sin;
  output Real integral;
algorithm
  integral :=(x2-x1)*(integrand(x1) + integrand(x2))/2;
end quadrature;

partial function Integrand
  input  Real x;
  output Real y;
end Integrand;

A functional argument can be provided in one of the following forms to be passed to a formal parameter of function type in a function call (see examples below):

1. as a function name,
2. as a function partial application,
3. as a function that is a component,
4. as a function partial application of a function that is a component.

In all cases the provided function must be "function type compatible" to the corresponding formal parameter of function type. Example:

// A function as a positional input argument according to case (a)
function Parabola
   extends Integrand;
algorithm
   y = x*x;
end Parabola;

area = quadrature(0, 1, Parabola);

// The quadrature2 example below uses a function integrand that
// is a component as input argument according to case (c):
function quadrature2 "Integrate function y=integrand(x) from x1 to x2"
  input  Real x1;
  input  Real x2;
  input  Integrand integrand;   // Integrand is a partial function type
  output Real integral;
algorithm
   integral := quadrature(x1,       (x1+x2)/2, integrand)+
               quadrature((x1+x2)/2, x2,       integrand);
end quadrature2;

A function partial application is a function call with certain formal parameters bound to expressions. A function partial application returns a partially evaluated function that is also a function, with the remaining not bound formal parameters still present in the same order as in the original function declaration. A function partial application is specified by the function keyword followed by a function call to func_name giving named formal parameter associations for the formal parameters to be bound, e.g.:

function func_name(..., formal_parameter_name = expr, ...)

[Note that the keyword function in a function partial application differentiates the syntax from a normal function call where some parameters have been left out, and instead supplied via default values.] The function created by the function partial application acts as the original function but with the bound formal input parameters(s) removed, i.e., they cannot be supplied arguments at function call. The binding occurs when the partially evaluated function is created. A partially evaluated function is "function compatible" to the same function where all bound arguments are removed [thus, for checking function type compatibility, bound formal parameters are ignored].

Example of function partial application as argument, positional argument passing, according to case (b) above:

model Test
   parameter Integer N;
   Real area;
algorithm
   area := 0;
   for i in 1:N loop
     area  := area + quadrature(0, 1, function Sine(A=2, w=i*time));
   end for;
end Test;

function Sine  "y = Sine(x,A,w)"
  extends Integrand;
  input Real A;
  input Real w;
algorithm
  y:=A*Modelica.Math.sin(w*x);
end Sine;

//Call with function partial application as named input argument:
area  := area + quadrature(0, 1, integrand = function Sine(A=2, w=i*time));

Example showing that function types are matching after removing the bound arguments A and w in a function partial application:

function Sine2  "y = Sine2(A,w,x)"
  input Real A;
  input Real w;
  input Real x; // Note: x is now last in argument list.
  output Real y;
algorithm
  y:=A*Modelica.Math.sin(w*x);
end Sine2;

// The partially evaluated Sine2 has only one argument:
// x - and is thus type compatible with Integrand.
area = quadrature(0, 1, integrand = function Sine2(A=2, w=3));

Example of a function partial application of a function that is a component, according to case (d) above:

partial function SurfaceIntegrand
   input Real x;
   input Real y;
   output Real z;
end SurfaceIntegrand;

function quadratureOnce
  input Real x;
  input Real y1;
  input Real y2;
  input SurfaceIntegrand integrand;
  output Real z;
algorithm
  // This is according to case (d) and needs to bind the 2nd argument
  z := quadrature(y1, y2, function integrand(y=x));
end quadratureOnce;

function surfaceQuadrature
  input Real x1;
  input Real x2;
  input Real y1;
  input Real y2;
  input SurfaceIntegrand integrand;
  output Real integral;
algorithm
   // Case (b) and (c)
   integral := quadrature(x1, x2,
     function quadratureOnce(y1=y1, y2=y2, integrand=integrand);
end surfaceQuadrature;

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.'model'

Define specialized class model

Examples

model SlidingMass
  parameter Modelica.SIunits.Mass m=1;
  parameter Modelica.SIunits.Force f=1;
  Modelica.SIunits.Position s;
  Modelica.SIunits.Velocity v;
  Modelica.SIunits.Acceleration a;
equation
  der(s) = v;
  der(v) = a;
  m*a = f;
end SlidingMass;

Syntax

   [ encapsulated ][ partial ] model
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

The keyword model is identical to the keyword class, i.e., no restrictions and no enhancements.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.'package'

Define specialized class package

Examples

package Library
  constant Real k = 0.1;

  type X = Real(min=0);

  model A
    ...
  end A;

  model B
    ...
  end B;
end Library;

Syntax

   [ encapsulated ][ partial ] package
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

May only contain declarations of classes and constants. Enhanced to allow import of elements of packages.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.'record'

Define specialized class record

Examples

  record States
    Modelica.SIunits.Position s;
    Modelica.SIunits.Velocity v;
  end States;

  record System
    parameter Modelica.SIunits.Mass m=1;
    parameter Modelica.SIunits.Force f=1;
    Modelica.SIunits.Acceleration a;
    States states;
  end System;

  model SlidingMass
    System sys;
  equation
    der(sys.states.s) = sys.states.v;
    der(sys.states.v) = sys.a;
    sys.m*sys.a = sys.f;
  end SlidingMass;

Syntax

   [ encapsulated ][ partial ] record
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

The keyword record is used to define records which are generally used in order to group variables. Only public sections are allowed in the definition or in any of its components (i.e., equation, algorithm, initial equation, initial algorithm and protected sections are not allowed). May not be used in connections. The elements of a record may not have prefixes input, output, inner, outer, or flow. Enhanced with implicitly available record constructor function. Additionally, record components can be used as component references in expressions and in the left hand side of assignments, subject to normal type compatibility rules.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Classes.'type'

Define specialized class type

Examples

type R0Plus = Real(min=0);

Syntax

   [ encapsulated ][ partial ] type
   IDENT class_specifier

class_specifier :
   string_comment composition end IDENT
   | "=" base_prefix name [ array_subscripts ] [ class_modification ] comment
   | "=" enumeration "(" ( [enum_list] | ":" ) ")" comment

See Modelica Language Specification for further details.

Description

The keyword type is used to define types, which may only be extensions to the predefined types, enumerations, array of type, or classes extending from type. Enhanced to extend from predefined types [No other specialized class has this property].

Extends from ModelicaReference.Icons.Information (Icon for general information packages).